Node / meshtastic / Meshtastic-Android / files / feature / firmware / src / commonMain / kotlin / org / meshtastic / feature / firmware / ota / UnifiedOtaProtocol.kt

Displaying Raw • Download

T8b949e/*

* Copyright (c) 2026 Meshtastic LLC

*

* This program is free software: you can redistribute it and/or modify

* it under the terms of the GNU General Public License as published by

* the Free Software Foundation, either version 3 of the License, or

* (at your option) any later version.

*

* This program is distributed in the hope that it will be useful,

* but WITHOUT ANY WARRANTY; without even the implied warranty of

* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

* GNU General Public License for more details.

*

* You should have received a copy of the GNU General Public License

* along with this program. If not, see <https://www.gnu.org/licenses/>.

*/

Tff7b72package T7ee787org.meshtastic.feature.firmware.ota

T8b949e/** Commands supported by the ESP32 Unified OTA protocol. All commands are text-based and terminated with '\n'. */

Tff7b72sealed Tff7b72class T56d364OtaCommand Tb4b4b4{

T8b949e/** Start OTA update with firmware size and SHA-256 hash */

Tff7b72data Tff7b72class T56d364StartOtaTb4b4b4(Tff7b72val Te6edf3sizeBytesTb4b4b4: Tffa657LongTb4b4b4, Tff7b72val Te6edf3sha256HashTb4b4b4: Tffa657StringTb4b4b4) Tb4b4b4: Te6edf3OtaCommandTb4b4b4(Tb4b4b4) Tb4b4b4{

Tff7b72override Tff7b72fun Td2a8fftoStringTb4b4b4(Tb4b4b4) Tff7b72= Ta5d6ff"Ta5d6ffOTA Tffd700$Te6edf3sizeBytesTa5d6ff Tffd700$Te6edf3sha256HashTa5d6ff\Ta5d6ffnTa5d6ff"

Tb4b4b4}

Tb4b4b4}

T8b949e/** Responses from the ESP32 Unified OTA protocol. */

Tff7b72sealed Tff7b72class T56d364OtaResponse Tb4b4b4{

T8b949e/** Successful response with optional data */

Tff7b72data Tff7b72class T56d364OkTb4b4b4(

Tff7b72val Te6edf3hwVersionTb4b4b4: Tffa657String? Tff7b72= Tff7b72nullTb4b4b4,

Tff7b72val Te6edf3fwVersionTb4b4b4: Tffa657String? Tff7b72= Tff7b72nullTb4b4b4,

Tff7b72val Te6edf3rebootCountTb4b4b4: Tffa657Int? Tff7b72= Tff7b72nullTb4b4b4,

Tff7b72val Te6edf3gitHashTb4b4b4: Tffa657String? Tff7b72= Tff7b72nullTb4b4b4,

Tb4b4b4) Tb4b4b4: Te6edf3OtaResponseTb4b4b4(Tb4b4b4)

T8b949e/** Device is erasing flash partition (sent before OK after OTA command) */

Tff7b72data Tff7b72object T56d364Erasing Tb4b4b4: Te6edf3OtaResponseTb4b4b4(Tb4b4b4)

T8b949e/** Acknowledgment for received data chunk (BLE only) */

Tff7b72data Tff7b72object T56d364Ack Tb4b4b4: Te6edf3OtaResponseTb4b4b4(Tb4b4b4)

T8b949e/** Error response with message */

Tff7b72data Tff7b72class T56d364ErrorTb4b4b4(Tff7b72val Te6edf3messageTb4b4b4: Tffa657StringTb4b4b4) Tb4b4b4: Te6edf3OtaResponseTb4b4b4(Tb4b4b4)

Tff7b72companion Tff7b72object Tb4b4b4{

Tff7b72private Tff7b72const Tff7b72val Te6edf3OK_PREFIX_LENGTH Tff7b72= T79c0ff3

Tff7b72private Tff7b72const Tff7b72val Te6edf3ERR_PREFIX_LENGTH Tff7b72= T79c0ff4

Tff7b72private Tff7b72const Tff7b72val Te6edf3VERSION_PARTS_COUNT Tff7b72= T79c0ff4

T8b949e/**

* Parse a response string from the device. Format examples:

* - "OK\n"

* - "OK 1 2.3.4 45 v2.3.4-abc123\n"

* - "ERASING\n"

* - "ACK\n"

* - "ERR Hash Rejected\n"

*/

Tff7b72fun Td2a8ffparseTb4b4b4(Te6edf3responseTb4b4b4: Tffa657StringTb4b4b4)Tb4b4b4: Te6edf3OtaResponse Tb4b4b4{

Tff7b72val Te6edf3trimmed Tff7b72= Te6edf3responseTb4b4b4.Te6edf3trimTb4b4b4(Tb4b4b4)

Tff7b72return Tff7b72when Tb4b4b4{

Te6edf3trimmed Tff7b72=Tff7b72= Ta5d6ff"Ta5d6ffOKTa5d6ff" Tff7b72-Tff7b72> Te6edf3OkTb4b4b4(Tb4b4b4)

Te6edf3trimmedTb4b4b4.Te6edf3startsWithTb4b4b4(Ta5d6ff"Ta5d6ffOK Ta5d6ff"Tb4b4b4) Tff7b72-Tff7b72> Tb4b4b4{

Tff7b72val Te6edf3parts Tff7b72= Te6edf3trimmedTb4b4b4.Te6edf3substringTb4b4b4(Te6edf3OK_PREFIX_LENGTHTb4b4b4)Tb4b4b4.Te6edf3splitTb4b4b4(Ta5d6ff"Ta5d6ff Ta5d6ff"Tb4b4b4)

Tff7b72when Tb4b4b4(Te6edf3partsTb4b4b4.Te6edf3sizeTb4b4b4) Tb4b4b4{

Te6edf3VERSION_PARTS_COUNT Tff7b72-Tff7b72>

Te6edf3OkTb4b4b4(

Te6edf3hwVersion Tff7b72= Te6edf3partsTff7b72[T79c0ff0Tff7b72]Tb4b4b4,

Te6edf3fwVersion Tff7b72= Te6edf3partsTff7b72[T79c0ff1Tff7b72]Tb4b4b4,

Te6edf3rebootCount Tff7b72= Te6edf3partsTff7b72[T79c0ff2Tff7b72]Tb4b4b4.Te6edf3toIntOrNullTb4b4b4(Tb4b4b4)Tb4b4b4,

Te6edf3gitHash Tff7b72= Te6edf3partsTff7b72[T79c0ff3Tff7b72]Tb4b4b4,

Tb4b4b4)

Tff7b72else Tff7b72-Tff7b72> Te6edf3OkTb4b4b4(Tb4b4b4)

Tb4b4b4}

Tb4b4b4}

Te6edf3trimmed Tff7b72=Tff7b72= Ta5d6ff"Ta5d6ffERASINGTa5d6ff" Tff7b72-Tff7b72> Te6edf3Erasing

Te6edf3trimmed Tff7b72=Tff7b72= Ta5d6ff"Ta5d6ffACKTa5d6ff" Tff7b72-Tff7b72> Te6edf3Ack

Te6edf3trimmedTb4b4b4.Te6edf3startsWithTb4b4b4(Ta5d6ff"Ta5d6ffERR Ta5d6ff"Tb4b4b4) Tff7b72-Tff7b72> Te6edf3ErrorTb4b4b4(Te6edf3trimmedTb4b4b4.Te6edf3substringTb4b4b4(Te6edf3ERR_PREFIX_LENGTHTb4b4b4)Tb4b4b4)

Te6edf3trimmed Tff7b72=Tff7b72= Ta5d6ff"Ta5d6ffERRTa5d6ff" Tff7b72-Tff7b72> Te6edf3ErrorTb4b4b4(Ta5d6ff"Ta5d6ffUnknown errorTa5d6ff"Tb4b4b4)

Tff7b72else Tff7b72-Tff7b72> Te6edf3ErrorTb4b4b4(Ta5d6ff"Ta5d6ffUnknown response: Tffd700$Te6edf3trimmedTa5d6ff"Tb4b4b4)

Tb4b4b4}

Tb4b4b4}

Tb4b4b4}

Tb4b4b4}

T8b949e/** Status updates during the OTA handshake. */

Tff7b72sealed Tff7b72class T56d364OtaHandshakeStatus Tb4b4b4{

T8b949e/** The device is erasing the flash partition. */

Tff7b72data Tff7b72object T56d364Erasing Tb4b4b4: Te6edf3OtaHandshakeStatusTb4b4b4(Tb4b4b4)

Tb4b4b4}

T8b949e/** Interface for ESP32 Unified OTA protocol implementation. Supports both BLE and WiFi/TCP transports. */

Tff7b72interface T56d364UnifiedOtaProtocol Tb4b4b4{

T8b949e/**

* Connect to the device and discover OTA service/establish connection.

*

* @return Success if connected and ready, error otherwise

*/

Tff7b72suspend Tff7b72fun Td2a8ffconnectTb4b4b4(Tb4b4b4)Tb4b4b4: Te6edf3ResultTff7b72<Tffa657UnitTff7b72>

T8b949e/**

* Start OTA update process.

*

* @param sizeBytes Total firmware size in bytes

* @param sha256Hash SHA-256 hash of the firmware (64 hex characters)

* @param onHandshakeStatus Optional callback to report status changes (e.g., "Erasing...")

* @return Success if device accepts and is ready, error otherwise

*/

Tff7b72suspend Tff7b72fun Td2a8ffstartOtaTb4b4b4(

Te6edf3sizeBytesTb4b4b4: Tffa657LongTb4b4b4,

Te6edf3sha256HashTb4b4b4: Tffa657StringTb4b4b4,

Te6edf3onHandshakeStatusTb4b4b4: Te6edf3suspend Tb4b4b4(Te6edf3OtaHandshakeStatusTb4b4b4) Tff7b72-Tff7b72> Tffa657Unit Tff7b72= Tb4b4b4{Tb4b4b4}Tb4b4b4,

Tb4b4b4)Tb4b4b4: Te6edf3ResultTff7b72<Tffa657UnitTff7b72>

T8b949e/**

* Stream firmware binary data to the device.

*

* @param data Complete firmware binary

* @param chunkSize Size of each chunk to send (256-512 for BLE, up to 1024 for WiFi)

* @param onProgress Progress callback (0.0 to 1.0)

* @return Success if all data transferred and verified, error otherwise

*/

Tff7b72suspend Tff7b72fun Td2a8ffstreamFirmwareTb4b4b4(Te6edf3dataTb4b4b4: Te6edf3ByteArrayTb4b4b4, Te6edf3chunkSizeTb4b4b4: Tffa657IntTb4b4b4, Te6edf3onProgressTb4b4b4: Te6edf3suspend Tb4b4b4(Tffa657FloatTb4b4b4) Tff7b72-Tff7b72> Tffa657UnitTb4b4b4)Tb4b4b4: Te6edf3ResultTff7b72<Tffa657UnitTff7b72>

T8b949e/** Close the connection and cleanup resources. */

Tff7b72suspend Tff7b72fun Td2a8ffcloseTb4b4b4(Tb4b4b4)

Tb4b4b4}

T8b949e/** Exception thrown during OTA protocol operations. */

Tff7b72sealed Tff7b72class T56d364OtaProtocolExceptionTb4b4b4(Te6edf3messageTb4b4b4: Tffa657StringTb4b4b4, Te6edf3causeTb4b4b4: Te6edf3Throwable? Tff7b72= Tff7b72nullTb4b4b4) Tb4b4b4: Te6edf3ExceptionTb4b4b4(Te6edf3messageTb4b4b4, Te6edf3causeTb4b4b4) Tb4b4b4{

T8b949e/** Transport-level connection to the device failed or was lost. */

Tff7b72class T56d364ConnectionFailedTb4b4b4(Te6edf3messageTb4b4b4: Tffa657StringTb4b4b4, Te6edf3causeTb4b4b4: Te6edf3Throwable? Tff7b72= Tff7b72nullTb4b4b4) Tb4b4b4: Te6edf3OtaProtocolExceptionTb4b4b4(Te6edf3messageTb4b4b4, Te6edf3causeTb4b4b4)

T8b949e/** The device returned an error response for a specific OTA command. */

Tff7b72class T56d364CommandFailedTb4b4b4(Tff7b72val Te6edf3commandTb4b4b4: Te6edf3OtaCommandTb4b4b4, Tff7b72val Te6edf3responseTb4b4b4: Te6edf3OtaResponseTb4b4b4.Te6edf3ErrorTb4b4b4) Tb4b4b4:

Te6edf3OtaProtocolExceptionTb4b4b4(Ta5d6ff"Ta5d6ffCommand Tffd700$Te6edf3commandTa5d6ff failed: Tffd700${Te6edf3responseTb4b4b4.Te6edf3messageTffd700}Ta5d6ff"Tb4b4b4)

T8b949e/** The device rejected the firmware hash (e.g. NVS partition mismatch). */

Tff7b72class T56d364HashRejectedTb4b4b4(Tff7b72val Te6edf3providedHashTb4b4b4: Tffa657StringTb4b4b4) Tb4b4b4:

Te6edf3OtaProtocolExceptionTb4b4b4(Ta5d6ff"Ta5d6ffDevice rejected hash: Tffd700$Te6edf3providedHashTa5d6ff (NVS mismatch)Ta5d6ff"Tb4b4b4)

T8b949e/** Firmware data transfer did not complete successfully. */

Tff7b72class T56d364TransferFailedTb4b4b4(Te6edf3messageTb4b4b4: Tffa657StringTb4b4b4, Te6edf3causeTb4b4b4: Te6edf3Throwable? Tff7b72= Tff7b72nullTb4b4b4) Tb4b4b4: Te6edf3OtaProtocolExceptionTb4b4b4(Te6edf3messageTb4b4b4, Te6edf3causeTb4b4b4)

T8b949e/** Post-transfer firmware verification failed on the device side. */

Tff7b72class T56d364VerificationFailedTb4b4b4(Te6edf3messageTb4b4b4: Tffa657StringTb4b4b4) Tb4b4b4: Te6edf3OtaProtocolExceptionTb4b4b4(Te6edf3messageTb4b4b4)

T8b949e/** An OTA operation did not complete within the expected time window. */

Tff7b72class T56d364TimeoutTb4b4b4(Te6edf3messageTb4b4b4: Tffa657StringTb4b4b4) Tb4b4b4: Te6edf3OtaProtocolExceptionTb4b4b4(Te6edf3messageTb4b4b4)

Tb4b4b4}